feat(collections): implement IDictionary<TKey,TValue> on the dictionary family - #338

Closes #307.

The set family got the mutable interface (ISet<T>) in 2.2.0 and is getting the read-only one in #306. The dictionary family had the inverse gap: IReadOnlyDictionary<,> and not IDictionary<,>. Since IDictionary<,> does not derive from IReadOnlyDictionary<,>, passing any Celerity dictionary except BTreeDictionary to an existing API taking IDictionary<,> was a hard compile error — the same Guiding Principle #3 drop-in defect, one level up.

What changed

Collection (src/Celerity/Collections/) — nine types now declare IDictionary<TKey, TValue?> alongside IReadOnlyDictionary<TKey, TValue?>: CelerityDictionary, SwissDictionary, RobinHoodDictionary, HashCachingDictionary, PooledCelerityDictionary, SmallDictionary, IntDictionary, LongDictionary, EnumMap. Every member is an explicit-interface forwarder onto the existing public surface — no existing public signature moved, and the concrete indexer still returns the non-nullable TValue (IndexerReturnTypeTests passes untouched).

Semantics, all matching Dictionary<,>:

Two design calls worth flagging for review:

1. The views were widened, not wrapped. KeyCollection / ValueCollection went from IEnumerable<T> to ICollection<T> rather than getting a separate boxed adapter type. That keeps dict.Keys allocation-free on the direct path while the interface-typed Keys still hands back a read-only collection. Contains, CopyTo and IsReadOnly are public on the views, and CopyTo(KeyValuePair<TKey, TValue?>[], int) is public on the dictionaries — mirroring BTreeDictionary, which already had both.

2. EnumMap is in, not out. The issue flagged its bounded key universe as a possible reason to leave it out. An out-of-range enum cast is rejected with ArgumentOutOfRangeException, which is an ArgumentException — the failure IDictionary<,>.Add already documents for a key it cannot accept — so this is an honest implementation, not a member that throws where the contract says it should not. Documented in the API reference and pinned by EnumMap_InterfaceAdd_ShouldRejectOutOfRangeKey.

Deliberately excluded, stated in the test class doc and the ROADMAP: FrozenCelerityDictionary (immutable), LruCache (evicts on insert, so Add could silently drop an unrelated entry), CelerityMultiMap (many values per key), and Trie<TValue> — the one genuine one-value-per-key mutable dictionary left out, because its Keys / Values are lazy IEnumerable<T> traversals rather than counted struct views, so widening them is a design change rather than a forwarder. Worth its own issue if wanted.

Parity rollout

• Cross-collection tests — new src/Celerity.Tests/Collections/DictionaryInterfaceTests.cs: the mirror of ReadOnlyDictionaryInterfaceTests. One row per dictionary drives the whole interface surface against a Dictionary<,> oracle, plus the bind-to-an-IDictionary<,>-parameter case the issue reports as a compile error, EnumMap's out-of-range key, the disposed-PooledCelerityDictionary corner, and the no-version-bump-on-overwrite rule through the interface indexer. BTreeDictionary joins the suite so the family contract is asserted in one place rather than drifting per type.
• Dedicated tests — no new type shipped, so the existing per-type files are unchanged; the interface is a family-wide contract and belongs in the shared suite. Every other shared suite (AddAndTryAddTests, ContainsValueTests, IndexerReturnTypeTests, LoadFactorBoundaryTests, RemoveOutValueTests, ClearNoOpVersionTests, …) covers concrete members that did not change; all pass untouched.
• Native AOT — Celerity.AotSmokeTest now drives the whole interface surface across the seven int-keyed dictionaries plus the long- and enum-keyed shapes. Worth having: Keys / Values are readonly structs reached through ICollection<T>, so the interface path boxes them and dispatches through an unboxing stub ILC has to generate — a foreach over the concrete type never compiles that path. All three aot-publish legs pass.
• Benchmarks — none added, as the issue scoped: these are explicit-interface members with no change to any concrete hot path, so a benchmark would measure interface-dispatch boxing rather than a Celerity property. No Program.cs registration needed.
• Dashboard — N/A: no new collection, so no COLLECTIONS entry in web/dev/bench/index.html / detail.html and no new ship card in web/index.html.
• Docs — docs/api/collections.md gains an IDictionary<TKey, TValue?> section (semantics table, read-only views, nullability note, runnable example) under CelerityDictionary, the declaration fences and peer prose updated for all nine types, and an EnumMap bounded-universe caveat. README.md: the "All dictionaries implement…" paragraph, the API-surface paragraph, and the stale "BTreeDictionary<,> also implements the mutable IDictionary<,>" sentence under "Choosing a collection".
• CHANGELOG — four [Unreleased] → ### Added bullets (interface, public CopyTo / view members, tests, docs).
• ROADMAP — the drop-in-parity bullet now records the dictionary half as done with the two design calls; the set half stays in-progress behind Implement IReadOnlySet<T> on the ten mutable sets #306.

Test plan

• dotnet build — clean, 0 warnings on Celerity.dll across net8.0 / net9.0 / net10.0
• dotnet test — 5242 passed, 0 failed on all three TFMs
• Coverage — 100.00% line / 100.00% branch via coverage.runsettings + scripts/coverage_report.py at the 100/100 floor
• dotnet pack -c Release — EnablePackageValidation against the 2.4.0 baseline passes; the change is additive and binary-compatible
• CI matrix (build + test across the TFM matrix, coverage gate, benchmarks, AOT smoke test)
• No gh-pages dashboard refresh expected on merge — no benchmark class was added or renamed

🤖 Generated with Claude Code